/**
 * @file mqtt_client.h
 * @brief Header file for handling MQTT protocol.
 *
 * This file contains the necessary declarations and functions for processing
 * the MQTT protocol. It provides the interface for connecting, subscribing,
 * publishing, and managing MQTT messages.
 *
 * @note Refer to other files for additional information and implementation details.
 *
 * @copyright Copyright (C) 2024 XH Technology Inc. All Rights Reserved 
 * @author Xie Jinhui
 * @version V1.0
 * @date 12/26/2024
 */

/* 
 * Header guard macro definition to prevent multiple inclusion of this header file
 * This standard C preprocessor technique ensures the contents are compiled only once
 * even if the header is included multiple times in different source files
 */
#ifndef MQTT_CLIENT_H

/* 
 * Define the header guard macro that marks the beginning of the protected section
 * Once this macro is defined, subsequent includes of this file will be skipped
 * by the preprocessor, preventing duplicate symbol definitions and compilation errors
 */
#define MQTT_CLIENT_H

/* 
 * Include the cJSON library header for JSON parsing and manipulation capabilities
 * cJSON provides lightweight JSON data structure handling for creating, parsing,
 * and modifying JSON objects and arrays in C applications
 */
#include "cJSON.h"

/* 
 * Include common utility definitions and shared data types
 * This header likely contains common macros, type definitions, and utility
 * functions used across multiple modules in the application
 */
#include "common.h"

/* 
 * Define error message constant for token validation failures in MQTT subscriptions
 * This string is returned when the authentication token in a received MQTT message
 * does not match the expected token value, indicating potential security issues
 */
#define SUB_MESSAGE_TOKEN "tokenErr"

/* 
 * Define error message constant for MQTT subscription timeout conditions
 * This string is returned when no response is received within the expected
 * timeframe after publishing an MQTT message, indicating communication failure
 */
#define SUB_MESSAGE_TOKEN_TIME_OUT "sub topic message time out"

/* 
 * Define application control action constant for disabling applications
 * This string represents the command to deactivate an application while
 * keeping it installed in the system for potential future re-enablement
 */
#define APP_DISABLE "disable"

/* 
 * Define application control action constant for enabling applications
 * This string represents the command to activate a previously disabled
 * application, making it available for execution and system interaction
 */
#define APP_ENABLE "enable"

/* 
 * Define application control action constant for uninstalling applications
 * This string represents the command to completely remove an application
 * from the system, including all associated files and configuration data
 */
#define APP_UNINSTALL "uninstall"

/* 
 * Define maximum message length constant for MQTT communication buffers
 * This value specifies the maximum size in bytes for MQTT message payloads
 * and ensures proper memory allocation for message handling operations
 */
#define MESSAGE_MAX_LEN (2048)

/* 
 * Function declaration for generating formatted timestamp strings
 * @param buff: Character buffer where the timestamp string will be stored
 * @return: Integer status code indicating success (0) or failure (non-zero)
 * This function creates ISO 8601 formatted timestamp strings with
 * millisecond precision and timezone information for message tracking
 */
int get_timestamp(char *buff);

/* 
 * Function declaration for extracting integer values from JSON objects
 * @param pVal: Pointer to integer variable where extracted value will be stored
 * @param pjObject: Pointer to cJSON object containing the target value
 * @param strItem: String name of the JSON property to extract
 * @return: Boolean value indicating success (TRUE) or failure (FALSE)
 * This function safely retrieves integer values from JSON objects with
 * proper null checking and type validation to prevent runtime errors
 */
uint8_t GetItemInt(int *pVal, const cJSON *pjObject, const char *strItem);

/* 
 * Function declaration for extracting timestamp values from JSON objects
 * @param pVal: Pointer to time_t variable where timestamp will be stored
 * @param pjObject: Pointer to cJSON object containing the timestamp
 * @param strItem: String name of the JSON timestamp property to extract
 * @return: Boolean value indicating success (TRUE) or failure (FALSE)
 * This function handles timestamp values stored as strings in JSON format
 * and converts them to system time representation for internal processing
 */
uint8_t GetItemTimeStamp(time_t *pVal, const cJSON *pjObject, const char *strItem);

/* 
 * Function declaration for extracting string values from JSON objects
 * @param pVal: Character buffer where the extracted string will be copied
 * @param pjObject: Pointer to cJSON object containing the target string
 * @param strItem: String name of the JSON property to extract
 * @return: Boolean value indicating success (TRUE) or failure (FALSE)
 * This function safely copies string values from JSON objects with
 * buffer management and proper null-termination for string safety
 */
uint8_t GetItemStr(char *pVal, const cJSON *pjObject, const char *strItem);

/* 
 * Function declaration for executing shell commands and capturing output
 * @param cmd: String containing the shell command to be executed
 * @param result: Buffer where the command output will be stored
 * @return: Integer status code indicating success (0) or failure (non-zero)
 * This function provides system command execution capability with output
 * capture for integrating external tools and utilities with the application
 */
int shell_exec(char *cmd, char *result);

/* 
 * Function declaration for sending application installation messages via MQTT
 * @param app_name: String identifier for the target application
 * @param package_path: File system path to the application installation package
 * @param appsign: Digital signature for application authentication and verification
 * @param result: Buffer where the operation result message will be stored
 * @return: Integer status code indicating success (0) or failure (non-zero)
 * This function handles the complete MQTT communication workflow for
 * application installation including verification and status reporting
 */
int install_app_message(const char *app_name, const char *package_path, const char* appsign, char *result);

/* 
 * Function declaration for sending application control messages via MQTT
 * @param app_name: String identifier for the target application to control
 * @param control_action: String specifying the control operation to perform
 * @param appsign: Digital signature for operation authentication
 * @param result: Buffer where the control operation result will be stored
 * @return: Integer status code indicating success (0) or failure (non-zero)
 * This function manages application lifecycle operations such as enabling,
 * disabling, or uninstalling applications through MQTT command messages
 */
int control_app_message(const char *app_name, const char *control_action, const char* appsign, char *result);

/* 
 * Function declaration for retrieving application list information via MQTT
 * @param app_name: String identifier for the requesting application
 * @param result: Buffer where the application list data will be stored
 * @return: Integer status code indicating success (0) or failure (non-zero)
 * This function queries the system for currently installed applications
 * and returns a structured list with application metadata and status
 */
int get_app_list_info(const char *app_name, char *result);

/* 
 * Function declaration for retrieving application status information via MQTT
 * @param app_name: String identifier for the target application
 * @param result: Buffer where the status information will be stored
 * @return: Integer status code indicating success (0) or failure (non-zero)
 * This function queries the current operational status of a specific
 * application including running state, resource usage, and health metrics
 */
int get_app_status_info(const char *app_name,char *result);

/* 
 * Function declaration for retrieving application rights and permissions via MQTT
 * @param app_name: String identifier for the target application
 * @param result: Buffer where the rights information will be stored
 * @return: Integer status code indicating success (0) or failure (non-zero)
 * This function queries the security permissions and access rights assigned
 * to a specific application for system resource and API access control
 */
int get_app_rights_info(const char *app_name,char *result);

/* 
 * End of header guard conditional compilation section
 * This marks the termination point of the header file content that is
 * protected from multiple inclusion by the MQTT_CLIENT_H macro guard
 */
#endif //MQTT_CLIENT_H